Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/architecture/harmonia-store-structure.md`:
- Around line 56-57: The documentation incorrectly states that harmonia-file-fd
uses cap-tokio as the underlying capability provider, but the actual
implementation uses cap-std with an async wrapper, as confirmed by the crate's
Cargo.toml. Update the description at line 56 to replace "via cap-tokio" with
"via cap-std" to accurately reflect the real implementation. Also apply the same
correction at line 167 where the same inaccuracy appears.

In `@harmonia-cache/src/narlist.rs`:
- Around line 21-39: The get_nar_list function unconditionally treats the input
path as a directory by calling Dir::open_ambient_dir, which fails for file or
symlink paths that were previously supported. Check whether the path is a
directory before attempting to open it with Dir::open_ambient_dir; if it is not
a directory (i.e., it is a file or symlink), handle it appropriately by either
creating a DirSource from the file/symlink directly or passing the path
differently to list_deep. This preserves support for both directory and
non-directory roots as the previous implementation did.

In `@harmonia-file-fd/README.md`:
- Around line 3-15: The README documentation contains outdated references to
incorrect crate names and trait locations. Update line 3 to replace the
reference to `cap-tokio` with the correct async backend (the crate's async
`cap-std` wrapper). Update line 8 to replace `harmonia-file-core` with the
correct trait package name `harmonia-file-io-pure`. Update line 14 to replace
any remaining references to `cap-tokio` with the correct async backend. Ensure
all crate and trait references throughout the README accurately reflect the
actual implementation and dependencies used in this crate.

In `@harmonia-file-fd/src/sink.rs`:
- Around line 29-39: The create_regular_file method has a race condition where
the file is created first on line 34 and then permissions are set afterwards on
line 38-39, leaving a window where the file has default umask-derived
permissions. Instead of calling set_permissions after opening, set the desired
Unix mode atomically during the file creation by adding the mode to the
OpenOptions object before calling open_with. Remove the post-creation
set_permissions call and the associated Unix-specific conditional block that
follows it, replacing it with a method call on the opts object (such as mode()
or similar) that the cap::OpenOptions API provides to set permissions at
creation time.

In `@harmonia-file-fd/src/source.rs`:
- Around line 108-114: The file type determination logic is incorrectly treating
all non-directory and non-symlink files as Regular, which includes FIFOs,
sockets, and device nodes that cannot be safely opened as regular files. In the
file_type determination block around lines 108-114, replace the else clause that
defaults to FileType::Regular with an explicit check using meta.is_file() for
regular files, and add a new error case to return an unsupported file kind error
for any other type. This same issue propagates to the file opening code around
lines 127-133 where unsupported file kinds are then attempted to be opened,
which will be fixed by the fail-fast error from the first change preventing
those types from being labeled as Regular in the first place.
- Around line 134-136: The current code automatically uses mmap for all large
files (size > mmap::MMAP_THRESHOLD) via FileReader::Mmap creation, which is
unsafe for non-immutable sources. Refactor the file reading logic to make mmap
opt-in: add a configuration flag or mode parameter to DirSource/FileReader that
explicitly indicates whether the backing files are immutable, and only use
mmap::MappedFile::from_fd when this immutable mode is explicitly enabled. When
immutable mode is disabled (the default), use streamed reads instead of mmap
regardless of file size.

In `@harmonia-file-io-pure/src/serde_impl.rs`:
- Around line 51-56: The match statement on `h.file_type.as_deref()` currently
uses a catch-all pattern `_` that silently defaults all unknown values to
FileType::Regular, making it impossible to distinguish between a legitimately
missing "type" field (which should default to Regular) and an invalid "type"
value (which should fail deserialization). Change the pattern matching to
explicitly handle the None case separately—allowing it to default to
FileType::Regular—while returning a deserialization error for any unknown or
invalid string values encountered in the Some arm instead of silently coercing
them to Regular.
- Around line 19-23: The Opaque deserializer implementation is tightly coupled
to serde_json::Map, which breaks compatibility with non-JSON formats like
MessagePack or CBOR. Replace the hardcoded serde_json::Map deserialization in
the deserialize method of the Opaque impl block with serde::de::IgnoredAny,
which provides format-agnostic deserialization by consuming any value from any
serialization format without enforcing a specific type structure.

In `@harmonia-file-io-pure/src/source.rs`:
- Around line 68-71: The exists() method in the Source trait currently masks all
errors (permission denied, IO failures, etc.) as false by using is_ok() on the
Result from open(). Introduce a new error-aware method try_exists that returns
Result<bool, Error> to properly distinguish between "file not found" and actual
errors, then update the existing exists() method to call try_exists() and handle
only the "not found" error case as false while propagating or logging other
errors appropriately.

In `@harmonia-file-nar/README.md`:
- Around line 3-10: The README documentation references the retired
harmonia-file-core crate and its APIs (FileSystemSource, FileSystemSink,
MemoryTreeSource, and list_deep) instead of the current harmonia-file-io-pure
crate. Replace all occurrences of harmonia-file-core with harmonia-file-io-pure
throughout the README to ensure users follow the correct, non-deprecated APIs
and avoid compilation failures when implementing the documented examples.

In `@harmonia-file-nar/src/archive/byte_stream.rs`:
- Around line 44-59: The synchronous `path.is_dir()` call in the path handling
logic is blocking the async runtime worker thread, which can cause latency
issues. Replace this blocking filesystem check with a non-blocking variant by
wrapping the synchronous metadata check in `tokio::task::block_in_place()` to
prevent blocking the Tokio runtime, or by using an async metadata retrieval
method if available from the cap-std library being used.

---

Nitpick comments:
In `@harmonia-file-nar/src/archive/mmap.rs`:
- Around line 82-84: The `len()` method implemented in the struct needs a
corresponding `is_empty()` method to satisfy the `clippy::len_without_is_empty`
lint. Add an `is_empty()` method immediately after the `len()` method that
returns a boolean indicating whether the length is zero. The `is_empty()` method
should follow the standard Rust convention of returning true when self.len
equals zero and false otherwise.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@harmonia-cache/src/narlist.rs`:
- Line 21: The DirSource::open_path function in harmonia-file-fd/src/source.rs
uses tokio::fs::metadata() which follows symlinks, causing a root symlink
pointing to a directory to be incorrectly dereferenced and listed as the target
directory instead of as a symlink. Replace the tokio::fs::metadata() call with
tokio::fs::symlink_metadata() to avoid following symlinks and correctly identify
symlink-to-directory cases. Additionally, add a regression test case that
verifies a store path that is a root symlink to a directory is handled correctly
without being dereferenced.

In `@harmonia-file-nar/src/archive/restorer.rs`:
- Around line 17-28: The restore_to_sink function returns success immediately
after restoring the first root object without verifying that the parser has
reached EOF, which means a stream with a valid root followed by trailing events
or junk data is incorrectly accepted. After the restore_sink_event call
completes for the first root, add a check to ensure the parser has no remaining
events by calling parser.next().await and verifying it returns None, otherwise
return an appropriate error to indicate unexpected trailing data in the stream.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@harmonia-file-nar/src/archive/restorer.rs`:
- Around line 121-129: The test code creates file sinks and writes data using
`write_all()` without explicitly calling `shutdown()`, relying on the Drop impl
to commit data. However, production code at line 57 explicitly calls
`shutdown()`. To align tests with production behavior and ensure data
consistency, add an explicit `.shutdown().await.unwrap()` call after the
`write_all()` call in the file sink creation chain around lines 121-129. Apply
the same fix to the similar code block at lines 137-145 to maintain test parity
with production patterns and prevent silent data loss if the Drop impl changes.